home *** CD-ROM | disk | FTP | other *** search
/ Shareware Overload Trio 2 / Shareware Overload Trio Volume 2 (Chestnut CD-ROM).ISO / dir31 / vib-docs.zip / PLAY.DOC < prev    next >
Text File  |  1992-08-15  |  11KB  |  224 lines
  1.  
  2.  
  3.  
  4.  
  5.              HOW TO USE THE VIBRANTS PLAYERS IN ASSEMBLER LANGUAGE
  6.              ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
  7.  
  8. All Code & Data (C) Copyright 1992 Jens-Christian Huus. All Rights reserved. The
  9. contents of this directory is public domain, but may not be used for any commer-
  10. cial use whatsoever. In other words, if you want music for games - contact me!
  11.  
  12.  
  13.  
  14.  
  15.  
  16. INTRODUCTION                                                           Chapter 1
  17. ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
  18.  
  19. The Play-Driver supplied in this directory was programmed to accept all kinds of
  20. different players developed by VIBRANTS, for a wide range of soundcards on the
  21. PC and compatibles. The Play-Driver itself will display a lot of useful informa-
  22. tion about the module currently playing, making it a joy to use - not just for
  23. the plain listener, but also for the programmer who wants to use the module in
  24. his own assembler programs.
  25.  
  26.  
  27. WHERE TO FIND THE FILES NEEDED                                         Chapter 2
  28. ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
  29.  
  30. As soon as you execute the Play-Driver with a music-filename following it, you
  31. will be met with a screen containing information on both the data and the player
  32. currently loaded. Notice the version number and the type of player. The exten-
  33. sion used in the music-filename also refers to the specific Card-Player needed
  34. for playing the module. In the directory PLAYERS you will find the player that
  35. was used for this module, the name containing both the right version number and
  36. the extension matches the music-filename's extension. This is the player you can
  37. use together with the module you tested!
  38.  
  39. If you used a music-filename in the Play-Driver which loaded a module playing
  40. samples, you will need the sample block in the directory SAMPLES as well. This
  41. file matches the music-filename with the exception of the "D" in the extension,
  42. which has been exchanged with a "S" instead.
  43.  
  44. Now everything you need to do is to load the two (or three, if a sample block
  45. is needed) blocks into your program. The player always needs to be located in
  46. offset 0000h in a segment, but the musicdata can be located anywhere in the
  47. memory. The sample block must be put at a clean offset 0000h as well. Some of
  48. the older players for samples also requires the sample block to be put at a
  49. clean segment adress, Eg. 6000:0000 or the like, because of limitations in the
  50. DMA controller.
  51.  
  52.  
  53. HOW TO ACCESS THE PLAYER                                               Chapter 3
  54. ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
  55.  
  56. The player is called using a DOS-like call to segment offset 0000h and features
  57. multivoiced sound-effects as well as music in the background. The CALL to off-
  58. set 0000h uses functions compatible with as many soundcard players as possible.
  59. Some soundcard players needs an extra register here and there, Eg. in order to
  60. define the location of a possible sample block, but all in all, the players uses
  61. the same functions. These functions will be described in this chapter.
  62.  
  63. TIP: After loading the Player into an allocated segment, I personally use the
  64.      following way to call the player; If AX contains the segment of the Player
  65.      and I have label like "PLAYER dw 0,0", I always use a "MOV [PLAYER+2],AX"
  66.      to store the value. Then, every time I need to call the player, all I have
  67.      to do is to type "CALL DWORD PTR [PLAYER]". The following examples will use
  68.      the simpler "CALL PLAYER" though, in order to maintain a better overview.
  69.  
  70.  
  71. MAIN RESET
  72. ───────────────────────────────────────────────────────────────────────────────-
  73. This is a CALL you must activate once in your initialisation code. It is vital
  74. that you always remember it, as it both clears the soundcard AND sets some over-
  75. all internal registers. When calling the MAIN RESET routine you must precede it
  76. with a BX value containing the segment adress of the music data the player
  77. should read, plus a CX value with an offset value to the data in that segment.
  78.  
  79.         MOV     AH,0 (MAIN RESET)
  80.         MOV     BX,(Seqment adress of music data)
  81.         MOV     CX,(Offset in segment)
  82.       [ MOV     DX,(Segment adress of sample block) ]
  83.         CALL    PLAYER
  84.       [ JC      RESET_ERROR ]
  85.  
  86. The combination BX:CX will as previously mentioned allow you to place the music-
  87. data anywhere in the normal memory area. If the player uses a sample block (Eg.
  88. as a Sound Blaster player), you will need to specify the segment adress of this
  89. block in the DX register as well.
  90.  
  91. After calling the MAIN RESET routine, the carry will be set if an error occured
  92. during the access with the I/O ports. However, a missing soundcard can be the
  93. reason for this error as well. NOTE: The carry function is NOT available in the
  94. older AdLib players v00.10 and v01.14!
  95.  
  96.  
  97. RESET
  98. ────────────────────────────────────────────────────────────────────────────────
  99. Sometimes it will be handy to clear and stop not only the player but also the
  100. entire soundcard, f.ex. when exitting to DOS. This is exactly what this function
  101. has been designed to do:
  102.  
  103.         MOV     AH,1 (RESET)
  104.         CALL    PLAYER
  105.  
  106. In fact, this function does exactly the same as MAIN RESET, except from setting
  107. the BX:CX (and DX) registers.
  108.  
  109.  
  110. START
  111. ────────────────────────────────────────────────────────────────────────────────
  112. After CALL'ing the MAIN RESET routine you can send the sound output number by
  113. loading BX with the sound number. F.ex if you want to call music number 5, which
  114. could be a hiscore tune, then simply write:
  115.  
  116.         MOV     AH,2 (START)
  117.         MOV     BX,0005h
  118.         CALL    PLAYER
  119.  
  120. Note that all call ranges starts from 00h, meaning that FIVE tunes in a player
  121. should be called from 00h to 04h in BX. This routine is used for calling music
  122. as well as sfx, and can be designed for multivoiced effects. This, however,
  123. depends on the internal assignment of voices for the music and sfx.
  124.  
  125.  
  126. PLAY
  127. ───────────────────────────────────────────────────────────────────────────────-
  128. This is the CALL you must use in the runcode part of your program. In the Play-
  129. Driver you can see how many times a second the module should be called. Usually,
  130. the timer interrupt is used for this purpose.
  131.  
  132.         MOV     AH,3 (PLAY)
  133.         CALL    PLAYER
  134.  
  135.  
  136. TOGGLE
  137. ───────────────────────────────────────────────────────────────────────────────-
  138. While calling the player in your program it can sometimes be handy to pause the
  139. output, Eg. if the PAUSE button is pressed. Using the same BX value as used when
  140. calling START you can pause any part of the player's sound output, if playing at
  141. that time. Calling TOGGLE again with the same BX value will continue the sound
  142. from the point where you last paused it. F.ex, if you're playing a tune in the
  143. background with BX=2 and you're calling a descending sfx with BX=3, then...
  144.  
  145.         MOV     AH,4 (TOGGLE)
  146.         MOV     BX,0003h
  147.         CALL    PLAYER
  148.  
  149. ...will pause the sfx but still keep the music playing. Repeating the above code
  150. again will continue the sfx from where you stopped it, still without affecting
  151. the background music. Please note that some soundcard players does not continue
  152. with the effects before triggering the next note on.
  153.  
  154.  
  155. MAINVOL
  156. ───────────────────────────────────────────────────────────────────────────────-
  157. The main volume is the same as the volume controlled in the Play-Driver using
  158. the Up/Down keys. This volume function has first priority, meaning that any
  159. other volume commands occuring inside the player will keep beneath this volume.
  160. This makes it suitable for fading when changing screens in your program. The
  161. main volume can be set by choosing it from 00h - 3Fh in BL, with 00h being the
  162. loudest:
  163.  
  164.         MOV     AH,5 (MAINVOL)
  165.         MOV     BL,10h
  166.         CALL    PLAYER
  167.  
  168. The above code will set the main volume to 10h. Using this CALL you can fade
  169. all sound output up or down using your own simple BX loops, f.ex. when leaving
  170. the titlescreen page in a game. NOTE: When calling the RESET routine the main
  171. volume will always be reset to 00h (loudest).
  172.  
  173.  
  174. SCAN
  175. ───────────────────────────────────────────────────────────────────────────────-
  176. This is a simple detection routine you can call to check if the soundcard needed
  177. is actually present. The routine returns the CARRY SET if no card was detected
  178. for the player to use.
  179.  
  180.         MOV     AH,6 (SCAN)
  181.         CALL    PLAYER
  182.         JC      NO_CARD_PRESENT
  183.  
  184. You can use this function even before using the MAIN RESET function, it does not
  185. need any data from other blocks. The Play-Driver always calls this function be-
  186. fore starting any module. NOTE: The old AdLib player v00.10 does NOT support
  187. this function!
  188.  
  189.  
  190. DIFFICULTIES                                                           Chapter 4
  191. ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
  192.  
  193. The music player has been programmed to make minimum use of the stack. However,
  194. it DOES use a few CALL's inside the program, apart from saving the DS and ES
  195. segment registers on stack as well. Therefore, you must be sure your stack seg-
  196. ment allows a few bytes extra when calling the player.
  197.  
  198. Visible register usage by CALL's: AX, BX, CX, DX, DI, SI and BP.
  199.  
  200. The player does NOT use the stackregisters SS and SP directly.
  201.  
  202. All CALL's returns using the RETF commands, to ensure that your code segment
  203. value is safe. This means that you MUST call the player with a FAR label. If you
  204. try to call it with a NEAR label, your program will crash.
  205.  
  206.  
  207. CONTACT INFO                                                           Chapter 5
  208. ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
  209.  
  210. If you want to get in touch with me for some reason, either to comment on the
  211. players or to report a bug - or perhaps to share some knowledge in how to pro-
  212. gram the soundcards available for the PC, then write to:
  213.  
  214.         Jens-Christian Huus
  215.         Tranegaardsvej 71 A
  216.         2900 Hellerup
  217.         Denmark
  218.  
  219. NOTE: I am NOT interested in any kind of illegal swapping. Both the player, the
  220. driver and music data is the (C) Copyright of Jens-Christian Huus and may not be
  221. used commercially. If you want to use some music for games or demonstration pro-
  222. grams, you MUST get in touch with me first.
  223.  
  224.